Table of Contents Chapter1 General Description 1 Introduction 1 The Manual - A Learning Tool 2 General Hardware Information 3 Front Panel 3 Back Panel 4 Interior Configuration 4 The Diskette 4 Specifications 5 Care of the 2031 5 Care of the Diskettes 7 Unpacking the Disk Drive 7 Chapter 2 Preparing Your Disk Drive 9 Connecting the Disk Drive To The Computer 9 Performing the Power-On Test 10 Inserting The Diskette Into The 2031 12 The 2031 Performance Test 12 Chapter 3 Learinng How To Use Your Floppy Disk Drive 15 The Block Availability Map (BAM) 16 The Disk Operating System (DOS) 17 Disk Maintenance Commands 18 NEW 18 HEADER (BASIC 4.0 Direct Command) 20 Initializing The 2031 20 The Directory 20 LOAD$ 21 DIRECTORY (BASIC 4.0 Direct Command) 21 Printing The Directory 21 VALIDATE 22 COLLECT (BASIC 4.0 Direct Command) 22 COPY 23 COPY (BASIC 4.0 Direct Command) 24 CONCAT (BASIC 4.0 Direct Command) 24 RENAME 24 RENAME (BASIC 4.0 Direct Command) 25 SCRATCH 26 SCRATCH (BASIC 4.0 Direct Command) 26 iii Chapter 4 BASIC Commands For Data Handling 27 BASIC Commands Associated With Floppy Disk Drives 27 SAVE and DSAVE (Writing a Program to a Diskette) 28 LOAD and DLOAD (Reading a Program from a Diskette 29 VERIFY 30 OPEN 31 DOPEN 32 CLOSE 32 DCLOSE 33 Closing the Command Channel 33 Closing the Data Channel 34 PRINT# 34 INPUT # 36 GET# 37 RECORD# 37 Quickload Feature (BASIC 4.0) 38 Moving A Tape Program to Disk 39 Chapter 5 Advanced Disk Programming 41 Commodore Disk Operating System (DOS) 41 Disk Utility Command Set 42 BLOCK-READ 44 BLOCK-WRITE 44 BLOCK-EXECUTE 45 BUFFER POINTER 45 BLOCK-ALLOCATE 45 MEMORY 46 MEMORY-WRITE 46 MEMORY-READ 47 MEMORY-EXECUTE 47 USER 47 File Types 49 File Formats 49 Chapter 6 Advanced File Handling 55 Special Open and Close Statements for Direct Access 55 Random Access Example 56 To create A File 57 To Add A Record 58 To See A Record 59 To Change A Record 60 iv Getting The Directory of Listings 60 Ending the Program 60 Relative Files 60 Relative File Components 61 Side Sectors 61 Relative File Expansion 61 I O Channels 62 Spanning 63 Print Termination 63 Creating A Relative File 65 Expanding A Relative File 65 Accessing A Relative File 66 Chapter 7 Simplifying The Use Of Commodore Disk Related Commands 71 Loading The DOS Support Program 71 Using The DOS Support Symbols: > and @ 71 Loading the Program With The / 73 Loading And Running A Program With Up Arrow 73 Special DOS Support Information 73 Changing Device Number 74 Chapter 8 Error Messages - Pattern Matching File Names - Disk Commands 75 Requesting Error Messages: Commodore Disk Drives 75 Description of DOS Messages 77 Pattern Matching 80 User's Quick Reference: Disk Commands 82 Chapter 9 Random Example Program Listing 85 Chapter 10 Index 91 List of Illustrations Figure Title Page 1 Model 2031 Rear View 8 2 Floppy Disk Hookup 10 3 Position for Diskette Insertion 11 4 Expanded View of a Single Sector 53 v List of Tables Table Title Page 1 Suggested Reading List 4 2 Specifications: Model 2031 Single Drive Floppy Disk 6 3 Standard Jump Table 48 4 Block Distribution By Track 50 5 2031 BAM Format 50 6 2031 Directory Header 51 7 Directory Format 51 8 Directory Entry Format 52 9 Sequential Format 52 10 Program File Format 52 11 Relative File Format 62 vi Chapter 1 GENERAL DESCRIPTION INTRODUCTION With the purchase of your Commodore 2031 Floppy Disk Drive, you have greatly enhanced the computing power of your disk-oriented Commodore Computer system. The system has been designed around the central concept of providing you, the user, with large file-handling capabilities supported by BASIC programming commands and furhter simplified by Disk Operating Sys- tem (DOS) Support command abbreviations. Because th edisk drive is an "intelligent" peripheral device, its operation requires no additional space in the computer's memory. This means you have just as much computer memory available to you as when the disk drive is not attached. When the disk krive is properly interface to a Commodore Computer, YOU become an important element of the system. Your importance, however, is measured directly with how well you understand how to effectively utilize the hardware and software. That's why it is best to think of your computer and disk drive as only part of a system. Grasping and understanding the concept that each individual component acts and reacts to signals and commands from other devices in the system will accelerte your fundamental grasp of how to operate, control, and master the system. This concept forms the basis of this manual: teaching you how to gain mastery of the system so that it will perform as desired. That is the reason this manual is organized in a building block fashion; it permits you to advance as fast as you desire. 1 To get the most out of your system you should study your Computer User's Guide and, if necessary, obtain selected manuals listed in Table 1. You will benefit most if you first read through this enteire manual before attempting to operate the Disk Drive. THE MANUAL - A LEARNING TOOL This manual is designed to encourage the concept of learning by doing. Difficult concepts and procedures have been broken down into simpler steps that lead the user through examples which provide ample opportunity to experiment later by returning to each command description. When possible, the command format has been included with te command description and, as an additional aid, a User's Quick Reference has been placed in Chapter 8 for easy access if problems persist. The first chapters discuss basic hardware freatures and permit you, right from the start, to become familiar with the disk drive by doing the performance tests which comprise the first essential "hands on" experience. Then, by actually using your particular disk drive and learning to carefullly follow instructions, you can gain the necessary confidence to proceed to more comprehensive subjects. By the time you begin Chapter 3, Learning How To Use Your Floppy Disk Drive, you will have already used some portions of the DOS Support sytem which is fully described in Chapter 7. It is actually easier to instruct a new user by using the simplified command structure of DOS Support than attempting to explain the entire command hierarchy at an early stage. This concept of provid- ing you with enough essintial information to complete a task, a step-by-step description of the task, and meaningful examples is a feature of this manual which wil provide you with sufficient incetive to actually complete the task. Problems are often accompanied with error messages. These error messages are contained in Chapter 8 where they can be quickly referenced, if needed. The Error Message discussions have been expanded to include: * How to request error messages. * Error message summary. * Detailed error message descriptions. For those users who have been reluctant to attempt disk programming because of the presumed degree of difficulty, note that the entire disk command hie- rarchy is structured in this manual from the least difficult to the more complex: 2 * Commands for file manipulation and maintenance * Commands for data handling * Advanced programming * Advanced file handling * Simplified commands Users who have attained some degree of programming skills may desire to begin with the advanced subjects such as random access or relative files while others may be content with just following the manual's format. In either case, this manual has been structured to provide the user with essential information in a logical sequence. Follow the examples, attempt the step-by-step procedures, and learn by doing. GENERAL HARDWARE INFORMATION The CBM model 2031 Floppy Disk Drive, described in this manual, is a 170 K-byte capacity storage device. Its primary components consist of read/write controls, drive motor electronics, one drive mechanism, one read/write head, and a track positioning mechanism. Also, the disk drive conforms to IEEE-488 interface requirements. For ease of reference, the Model 2031 Single Floppy Disk Drive will be referred to in this manual as "the 2031". The 2031 is operationally compatible with the following Commodore Computers: 1. Series 2001 -- 16K and 32K -- Operating With BASIC Version 3.0 2. Series 2001 -- PET 8K -- Upgraded to BASIC Version 3.0 3. Series 3000 -- 16K and 32K -- Operating With BASIC Version 3.0 4. Series 4000 -- PET 8K, 16K, and 32K -- Operating With BASIC Version 4.0 5. Series 8000 -- 32K -- Operating With BASIC Version 4.0 FRONT PANEL The disk drive's front panel consists of an identification paneel across the top, a slot in which to insert a diskette, and a door to close after insertind the diskette. When the door is closed, the diskette is clamped onto the diskette spindle hub. Also, there is a LED indicator light on the front panel. This light is called th Drive Active Indicator; it lights when the drive is active. This LED flashes continuously if an error has occurred; it wil extinguish after the error channel has been read. 3 Back Panel The back of the disk drive contains an IEEE-488 interface connector. Near the panel's lower edge is the power ON/OFF switch. There is also a "slow blow" fuse, and the AC power cord. Interior Configuration The interior of your 2031 contains a disk drive and all the necessary logic for disk operation. The mechanical device is, for the most part, located beneath the disk spindle. The Diskette The diskette (also known as a minifloppy, floppy diskette, minidiskette, etc.) is similar to the standard flexible disk. You should ensure that you buy diskettes for SOFT SECTORED FORMAT. Your Commodore dealer can supply your needs. Table I. SUGGESTED READING LIST ---------------------------------------------------------------------------------------------------------------- | | | Pet/CBM Personal Computer Guide. C.S. Donahue and J.K. Enger, | | Osborne/McGraw-Hill. 630 Bancroft Way, Berkeley, CA 94710 | | | | Hands-On Basic With A Pet. H.D. Peckman, McGraw-Hill, 1979 | | | | Entering BASIC. J. Sack and J. Meadows, Science Research Associates, | | 1973 | | | | BASIC: A Computer Programming Language. C. Pegels, Holden-Day, | | Inc., 1973 | | | | BASIC Programming. J. Kemeny and T. Kurtz, Peoples Computer Co., | | 1010 Doyle (PO Box 3100), Menlo Park, CA 94025, 1967 | | | | A Guided Tour of Computer Programming In BASIC. T. Dwyer, | | Houghton Miflin Co., 1973 | | | | Programming Time Shared Computer In BASIC. Eugene H. Barnett, | | Wiley-Interscience, L C 72-175789 | | (continued) | ----------------------------------------------------------------------------------------------------------------- 4 Table 1. Suggested Reading List (Continued) ----------------------------------------------------------------------------------------------------------------- | Programming Language #2. Digital Equipment Corp., Maynard MA | | 01754 | | | | 101 BASIC Computer Games. Software Distribution Center, Digital | | Equipment Corp., Maynard, MA 01754 | | | | What To Do After You Hit Return. Peoples Computer Co., 1010 Doyle | | (PO Box 3100), Menlo Park, CA 94025 | | | | Basic BASIC. James S. Coan. Hayden Book Co., Rochelle, Park NJ | | | | Workbooks 1-5 T.I.S., PO Box 921, Los Alamos, NM 87544 | | | | Programming The 6502. R. Zaks, Sybex, 1978 | | | | 24 Tested, Ready-To-Run Game Programs In BASIC. K. Tracton, Tab | | Books, 1978 | | | | Some Basic Programs. M. Borchers and R. Poole. Osborne & Assoc. | | Inc., 1978 | | | | The Channel Data Book. B. Lewis, 5950 Mandarin Ave., Goleta, CA | | 93017, 1978 | | | | PET And The IEEE 488 Bus (GPIP).Osborne/McGraw-Hill, 630 Ban- | | croft Way, Berkeley CA 94710 | ----------------------------------------------------------------------------------------------------------------- Specifications Table 2 contains the specifications for the 2031. CARE OF THE 2031 The disk drive should be placed on a flat surface free of vibration. It is important that dust particles be kept at a minimum since a particle buildup will interfere with optimum operation. If you should experience a hardware failure, contact your Commodore dealer. Any attempt to correct the problem yourself could result in voiding the warranty. 5 Table 2. SPECIFICATIONS: MODEL 2031 SINGLE DRIVE FLOPPY DISK ------------------------------------------------------------------------------------------------------------------------------- | | | STORAGE | | | | Total capacity 174848 bytes | | Sequential 168656 bytes | | Relative 167132 bytes; 65536 records per file | | Directory entries 144 | | Sectors per track 17 to 21 | | Bytes per sector 254 | | Tracks 35 | | Blocks 683 | | | | IC's: | | | | Controller and Interface | | 6502 microprocessor | | 6522 I/O, interval timers | | 6522 I/O, interval timers | | 2114 (4) 4x1K RAM | | | | PHYSICAL | | | | Material 18 ga. steel | | Dimensions | | Height 6.5" | | Width 15.0" | | Depth 14.35" | | | | ELECTRICAL | | | | Power requirements USA | | (domestic) | | Voltage 120 VAC | | Frequency 60 Hertz | | Power 50 Watts | | Power requirements | | (international) | | Voltage 100, 220, or 240 VAC | | Frequency 50 Hertz | | Power 50 Watts | | | | MEDIA: | | | | Diskettes Standard mini 5 1/4", single sided, | | single density | | | ------------------------------------------------------------------------------------------------------------------------------- 6 CARE OF THE DISKETTES Handle diskettes with care. Follow these instructions to maintain the quality of the diskette and to protect the integrity of the data: 1. Return the diskette to its storage envelope whenever it is removed from the drive. 2. Keep the diskettes away from magnetic fields. Exposure to a magnetic field can distort the data. 3. Never leave a diskette on top of your computer or disk drive. 4. Do not write on the plastic jacket with a lead pencil or ball-point pen. Use a felt tip pen or fill out the label before attaching it to the jacket. 5. Do not expose diskettes to heat or sunlight. 6. Do not touch or attempt to clean the diskette surface. Abrasions will cause loss of stored data. 7. Before applying power to the 2031, insure that there is no diskette in the drive. UNPACKING THE DISK DRIVE Before unpacking the disk drive, inspect the shipping carton for signs of external damage. If the carton is damaged, be especially careful when inspecting its contents. Carefully remove all packing material and the contents of the carton. DO NOT discard any packing material until you have made sure you have located all the contents of the carton! The carton should contain: 1. Commodore Single Floppy Disk Drive 2. User Manual, Number 2031036 3. A 2031 TEST/DEMO diskette If any items are missing, please contact your Commodore dealer immediately. 7 Figure 1. Model 2031 Rear View 8 CHAPTER 2 PREPARING TO USE YOUR DISK DRIVE Before starting to use your disk drive, make sure it is in good working condition. This includes properly connecting it to your computer, giving it a power-on and initial checkout test, and finally the performance test using the appropriate TEST/DEMO diskette. CONNECTING THE DISK DRIVE TO THE COMPUTER One of two connector cables are required to interface the floppy to the compu- ter. These cables can be supplied by your Commodore dealer. 1. PET-to-IEEE cable P.N 320101 Use this cable if the disk drive is to be the only (or first) IEEE device connected to your computer. 2. IEEE-to-IEEE cable, P/N 905080 Use this cable if your disk drive is to be connected ("daisy chained") to another peripheral device such as the Commodore Model 2022, or any other suitable interfaced printer. 9 Follow these steps to connect the disk drive to you computer: STEP 1. Turn power OFF to the computer. STEP 2. Place the disk in a convenient location as close as possible to the computer. DO NOT connect the disk drive to a power outley at this time (see Figure 2). STEP 3. Connect the PET-to-IEEE cable between the IEEE-488 interface connector on the ocmputer and the connector on the disk drive. If additional IEEE devices are to be connected, the IEEE-to-IEEE cable(s) must be used. STEP 4. Connect the disk drive power cable to an AC outlet. DO NOT turn on power at this time. Figure 2. Floppy Disk Hookup PERFORMING THE POWER-ON TEST You are now ready to proceed with the power-on part of the checkout: STEP 1. Open the disk drive door. Ensure that there is no diskette in the drive. STEP 2. Turn power ON to the COMPUTER and verify that it is working properly. 10 STEP 3. Apply power to the disk drive. The LED flashes to indicate a faulty condition. The number of flashes determine which component is faulty. The following lists the components and their respective number of flashes. Flash Code Component 1 zero page, U3B, U3D 2 ROM U5F 3 ROM U5H 4 RAM U3B, U3C, U3D, U3E NOTE If the problem persists, try disconnecting the other devices attached to the IEEE bus. This should assure that a problem related to another device does not affect the disk drive. Figure 3. Position for Diskette Insertion 11 INSERTING THE DISKETTE INTO THE 2031 Caution NEVER APPLY POWER TO THE DISK DRIVE IF A DISKETTE IS PRESENT (LOCKED AND SEATED). STEP 1. Ensure that the power to the disk drive is OFF and DO NOT apply power until you complete this step. Open the disk drive door and ensure that no diskette is present in the drive. STEP 2. If the preceding conditions have been met, you may apply power to the disk drive. STEP 3. Insert the diskette into the slot with the write protect tab oriented to the left (see Figure 3) and push it competely in. STEP 4. Once the diskette is in the slot, GENTLY close the door partially to center the diskette. Repeat this centering action several times and then close the door firmly. The diskette is now seated and locked in the drive, ready for processing by the computer. STEP 5. To remove the diskette, insert your index finger under the lip of the door and gently PULL. This will release the door and permit access to the diskette. The diskette is now free to be removed from the drive. THE 2031 PERFORMANCE TEST Whenyou have successfully completed the Power-On test, proceed with the Performance Test. Don't worry if you don't fully understand exactly what is happening in this test. At this point, enter the commands just to get a feel for what you can do with your disk. If UNEXPECTED result are obtained during any step of the test, stop and start over again. The most likely cause of a problem is an improperly entered command. This is to be expected until you become familiar with your disk nit. All commands are entered via t5he keyboard and must be followed by a carriage return: press the RETURN key on your keyboard. NOTE Commands must be entered exactly as shown. DO NOT insert any spaces unless shown in the example. If the error indicator lights, you may be able to continue the example anyway. Re-enter your last command. If the light goes out, your correction was successful and you may continue. 12 NOTE FOR BUSINESS KEYBOARD USERS ONLY: You can set your com- puter for upper case character entry. Do this by typing: POKE 59468,12 and pressing the RETURN key. Although it is not absolutely necessary to give this command, it does permit easy entry. In addition, the examples in this manual can be duplicated exactly when you sue only upper case. If this step is omitted the display will be in lower case letters. DO NOT use the shift key when entering commands. STEP 1. Insert the DEMO diskette into the drive as previously instructed. STEP 2. Type: LOAD"*",8 and press RETURN. The computer will load the first file from the diskette in drive 0 and display the following: READY. LOAD"*",8 SEARCHING FOR * LOADING READY. STEP 3. Type: RUN and press RETURN. This will cause the DOS Support Program to be executed. (This program is not necessary for the disk unit to operate; it just simplifies the direct mode commands.) A brief introductory description of DOS Support is presented in Chapter 3 as it applies to Chapter 3 operations. A detailed description of DOS Support is presented in Chapter 7. STEP 4. Type: /PERFORMANCE TEST The screen will display: SEARCHING FOR PERFORMANCE TEST LOADING READY. STEP 5: Type: RUN and press RETURN. The program instructs you to place a blank diskette into the drive. The Performance Test Program executes a shortened version of the test used by Commodore in final inspection of the 2031. The purpose of this test is to ensure that the unit is functioning correctly and will take approxiamately seven minutes to complete. NOTE Do not use diskettes containing any valuable infor- mation since the Performance Test Program will re-format them and any data will be lost. The test program will label this diskette "Test Disk." This diskette is ready for further use when the test pro- gram is completed and the performance test has been satisfied. 13 The computer will first format the diskette. This procecure takes up to three minutes. At the end of the operation the screen displays: NEW-0 COMMAND OK 0 00.0 THE DRIVE PASSES THE MECHANICAL TEST The computer conducts the remainder of the Performance Test and displays: OPEN WRITE FILE ON 0 OK 0 00.00 WRITING DATA TO 0 OK 0 00.00 CLOSE WRITE DATA TO 0 OK 0 00.00 OPEN READ FILE ON 0 OK 0 00.00 READING DATA FROM 0 OK 0 00.00 SCRATCH FILE ON 0 OK 0 00.00 FILES SCRATCHED 1 01.00 WRITE TRACK XX ON 0 OK 0 00.00 WRITE TRACK 1 ON 0 OK 0 00.00 READ TRACK XX ON 0 OK 0 00.00 READ TRACK 1 ON 0 OK 0 00.00 UNIT HAS PASSED PERFORMANCE TEST! REMOVE DISKETTE FROM THE DRIVE BEFORE TURNING POWER OFF. READY. STEP 6. Remove the diskettes and return them to their protective jackets. The floppy has passed the Performance Test. STEP 7. If any problems have been encountered during this phase of the test, return to step 1 and repeat the entire procedure. If problems persist and you do not reach a satisfactory conclusion to the Performance Test, contact your Commodore dealer. 14 Chapter 3 LEARNING HOW TO USE YOUR FLOPPY DISK DRIVE Your CBM Floppy Disk Drive, which enhances your computing power with added storage and file handling capability, is controlled directly with: * BASIC commands entered via the keyboard * BASIC statements within programs * Special disk commands In this chapter you will learn how to apply those commands and statements. This chapter is organized in such a way that the functions and format of disk commands are described in a manner which permits the user to perform disk- related tasks. For BASIC 4.0 users, those BASIC commands which correspond to each disk maintenance command are also discussed. Before using your floppy disk make sure you know how to: 15 As changes occur to the BAM in DOS memory, the BAM on disk will be updated to reflect these changes. Updates to the BAM occur when a program is SAVEd or a CLOSE or DCLOSE is performed on a new RELative or SEQuen- tial data file. 1. Operate you Commodore Computer 2. Do elementary programming in BASIC 3. Open and close files. NOTE The BASIC statements described in this chaper apply specifically to the 2031. Certain commands and statements may follow a slightly different for- mat or produce different results from those des- cribed herein when they are used with the computer or with other peripherals. Consult the appropriate manual for the exact use of these commands and statements in other applications. This chapter will first acquaint the user with those fundamental disk commands that perform disk maintenance and file manipulation and will then progressively advance toward an understanding of those BASIC commands used for data handling. Approached in this manner, the user will then have developed the necessary confidence and programming skills to proceed to advanced disk pro- gramming techniques. Practice the disk commands, read the examples, and follow the step-by-step illustrations of their usage. The understanding of the more advanced disk programming techniques will depend to a large degree upon how well the fundamentals have been mastered. To facilitate your understanding and mastery of Commodore BASIC, two com- puter terms are stressed in this Chapter: Block Availability Map (BAM) and Disk Operating System (DOS). Although these are conventional terms, they will be briefly discussed as they relate to the Commodore Floppy Disk Drive. THE BLOCK AVAILABILITY MAP (BAM) The BAM is a disk memory representation of available and allocated space on a disk. When the system stores information on a disk, the BAM will be automati- cally referenced by the DOS to determine what space is available and how many blocks can be allocated. If sufficient space is available to store a given file, it will be stored on the disk and the BAM updated to account for the space allocated. However, if the DOS detects that a file will occupy more space than available, an error message will be generated. Formatting aa disk creates the BAM which is then loaded into DOS memory upon initialization. The BAM which is then loaded into DOS memory upon initialization. The BAM is stored on diskette on track 18, sector 0, and 128 bytes in length. 16 THE DISK OPERATING SYSTEM (DOS) The DOS is responsible for managing information exchange between disk con- troller and the computer. The DOS performs many functions which are transparent to the user but which are vital to the operation of the system. For example, the DOS monitors the input/output (I/O) of the disk so that channels are properly assigned and that no lengthy waits for an open channel occur. In addition to monitoring of disk I/O, the DOS also uses the channel structure to search the directory and to delete and copy files. There is another function of DOS called DOS Support which was used during hardware checkout in Chapter 2. Review the Performance Test procedure and observe the special symbols of DOS Support which were used to duplicate and initialize the disks before these procedures were fully explained to the user. Because of its ease of use, DOS Support symbols were easier to implement at that point than attempting to explain the programming procedures they replace. It is now appropriate to briefly discuss how DOS Support can enhance and simplify you knowledge of operating your Commodore computer. The first file on the TEST DEMO diskette that comes with your disk drive is the DOS SUPPORT PROGRAM. This program, when loaded into computer memory, permits the user to enter abbreviations from many disk commands. For example, disk commands which would normally be transmitted to the disk using the PRINT#1fn,”commandstring” format may be transmitted via DOS SUPPORT by preceding the command with > or @. Typing slash (/) followed by a program name and RETURN will cause DOS SUPPORT to load that program into memory. Replacing certain disk commands with DOS Support special symbols can simplify learning about your Commodore computer by providing a faster method to communicate with the disk. Chapter 7 contains detailed instructions concerning the use of these special symbols and their limitations. 17 DISK MAINTENANCE COMMANDS The following disk commands permit the user to perform file manipulation and disk maintenance. BASIC 4.0 DIRECT COMMAND FUNCTION COMMAND NEW Formats a disk HEADER INITIALIZE Prepare diskette for use ---- Diskette Level LOAD"$0" Read disk directory DIRECTORY VALIDATE Reconstruct Block Avail- COLLECT ability Map (BAM) COPY Copies files (optional COPY concatenation) CONCAT File Level RENAME Renames a file RENAME SCRATCH Erases a file SCRATCH NOTE Diskette commands can be transmitted to the disk by PRINT# commands or through the abbreviated commands of DOS support. The examples in this chapter assume that a file has been opened with the OPEN 15,8,15 command. If the error message ?FILE OPEN ERROR appears upon typing the OPEN command, it means that the logical file was opened but had not been properly closed. This error condition will automatically close the file; to re- cover, retype the OPEN command. NEW Each time a diskette is placed in the drive, both the diskette and the drive must be prepared for use. A previously unused diskette must first be formatted in the soft-sector format recognized by your particular disk drive. This may be accomplished by use of the NEW disk command. 18 Before using the NEW command to format the diskette and initialize the disk drive, enter the command: PRINT#15,"commandstring" where 15 is the logical file number of a file which has been opened to the disk command channel (primary address 8, secondary address 15). The format for NEW is: "NEWdr:fn,xx" or "Ndr:fn,xx" Where: dr = the drive number, 0 fn = the file name you wish to assign to the disk. It may be up to 16 characters long. xx = a unique two-character, alphanumeric identifier supplied by the user. The NEW command (with ID specified) is used on an unformatted diskette or one which the user wishes to reformat. NEW creates the block headers, writing the sync characters, disk ID, and track and sector numbers at the beginning of each block. The directory header and the BAM are created and the diskette is made ready to accept data. The command may be used on an already formatted diskette (with no ID specified) to clear the disk directory and reinitialize the BAM, deallocating all blocks on the diskette. The time involved in reformatting without an ID is much less than formatting with an ID. Example 1: OPEN15,8,15 PRINT#15;"N0:TEST DISK,88" These commands will open the command and error channel to the disk drive and format a disk, giving it a disk identifier of 88. Here's an example of reformatting a diskette using the NEW command and no disk ID. Example 2: OPEN1,8,15 PRINT#1,"N0:NEWNAME" The diskette will be assigned the name "NEWNAME" and the directory and BAM will be cleared. This procedure will work only if the idskette has been formatted. The NEW disk command SHOULD NOT be confused with the NEW command in BASIC. The latter will delete the program currently in memory and clear all variables before entering a new program. 19 HEADER (BASIC 4.0 DIRECT COMMAND) The HEADER command has the same effect as NEW command but is reserved for those computers using BASIC 4.0. Since formatting destroys all data pre- viously stored, the HEADER commands has a built-in safety feature that que- ries the user: ARE YOU SURE? A positive response to theis questino permits formating to take place while a gegative response aborts the operation. The format for the HEADER COMMAND IS: HEADER"fn",Ddr,Ixx,Udn Where: fn = file name supplied by user but limited to 16 characters. dr = drive number, 0 xx = a unique two character alphanumeric identifier (ID) supplied by user. (same parameters as used by NEW command) dn = device number (Defaults to 8) Initializing the 2031 The 2031 uses a hardware feature to detect the removal or insertion of a diskette, so it is not necessary to initialize since this is an automatic function. THE DIRECTORY Confirm that the newly formatted disk has the correct ID and disk name by using one of the following methods to list the directory. The directory display includes the following information: * Disk Name * Disk ID * DOS version number * File Name * File type * Number of blocks used * Number of available (free) blocks There are two methods available to all users for listing the directory. The first method illustrates the listing procedure using LOAD and the second, the listing procedure in BASIC 4.0 using the DIRECTORY command. 20 LOAD$ This procedure will destroy any program currently in computer memory when the directory is LOADed. (Refer to the description of the >$ DOS Support command in Chapter 7 which is a non-destructive directory display procedure.) STEP 1: Place a formatted disk in the drive. STEP 2: Type: LOAD"$0",8 (or LOAD"$",8) then press RETURN. The screen displays: LOAD"$0",8 SEARCHING FOR $0 LOADING READY STEP 3: Type: LIST The drive directory will be displayed. DIRECTORY (BASIC 4.0 DIRECT COMMAND) This command will display the directory without disturbing the content of the memory. You may type: DIRECTORY D0 using the full word spelling but the preferred shor format is illustrated which uses the first two unshifted characters followed by a shifted R. To display the directory, type: diRd0 ON Udn and press RETURN. If using upper case display, type: DI-D0 ON Udn and press RETURN. The - in this example represents the upper case display for a shifted R. See your BASIC 4.0 reference manual for a complete description of this BASIC command. Printing The Directory Quite often, it becomes convenient to affix a diskette directory listing directly on the protective jacket. This permits the user to scan the printed directory listing without having to insert the diskette into the drive to obtain this information. Should you desire to print the directory, place the diskette in the drive and enter the following commands: LOAD"$0",8 Loads the directory OPEN 4,4:CMD4 Opens device 4 (printer) and changes the primary output device to 4. LIST Prints the directory. PRINT#4:CLOSE4 Returns output to the screen and closes the file. 21 VALIDATE The VALIDATE command traces through each block of data contained in all files on the diskette. If this trace is successful, a new BAM is generated in the disk memory and written to the diskette. Any blocks which have been allocated but are not associated with a file name, as in the case of direct access files will be freed for use. This will not affect relative files created using the BASIC 4.0 DOPEN command. In addition to reconstructing the BAM, VALIDATE deletes files from the direc- tory that were never properly closed. If a READ error is encountered during a VALIDATE, the operation aborts and leaves the diskette in its previous state. If a VALIDATE error does occur, you must re-initialize before proceeding. The format for VALIDATE is: PRINT#15,"VALIDATEdr" Where: dr = drive number 0 NOTE You may abbreviate VALIDATE to V. Example: OPEN1,8,15 PRINT#1,"V0" or PRINT#1,"VALIDATE 0" COLLECT - (BASIC 4.0 Direct Command) The COLLECT command in BASIC 4.0 performs the same function as VALI- DATE. Either command will accomplish the following: * Recreate a Block Availability Map according to valid data on disk * Delete files from the directory which were never properly closed (OPENed but never CLOSEd) The format for COLLECT is: COLLECT Dx ON Udn Where: x = drive number 0 Example: COLLECT D0 ON Udn Verifies the drive (drive defaults to 0) 22 COPY The COPY command allows you to reproduce files on the diskette or to create multiple copies (under different names). This command can also be used to concatenate data files. Up to four files can be concatenated into the destination file. The COPY command may be abbreviated with a C. COPY disk command can be formatted three ways depending upon application. To copy a single file: PRINT#1fn,"COPYddr:dfn=sdr:sfn" or PRINT#1fn,"Cddr:dfn=sdr:sfn" NOTE The source (sdr) and the destination (ddr) drives are the same. To concatenate and copy PRINT#1fn,"Cddr:dfn=sdr:sfn,sdr:sfn... Where: ddr = is the destination drive (0). dfn = is the destination file name. This name must be different than the old file name since both files will reside on the same diskette. In example 1, a file is reproduced on the diskette. In example 2, two files are concatenated into one file. An error message (FILE EXISTS) will be generated in the disk unit if a file to be copied already exists on the diskette. Example 1: PRINT#1,"C0:ACCT1=0:ACCT" A file is reproduced on the diskette. Example 2: PRINT#1,"C0:JDATA=0:ADATA,0:BDATA" Two files are concatenated into one file. Note that file names should be short since the maximum length of a disk command string is 58 characters. 23 COPY - (BASIC 4.0 Direct Command) The COPY direct command in BASIC 4.0 performs the same function as COPY disk command and its format is also dependent upon application. Use this format to copy a single file: COPY Dsdr,"sfn" to Dddr,"dfn" ON Udn Where sdr = the source diskette (0) ddr = destination diskette (0) fn = file name Again, notice that the source (sdr) and the destination (ddr) are the same. CONCAT (BASIC 4.0 Direct Command) The CONCAT direct command is BASIC 4.0 permits the user to concatenate files. The format for CONCAT is: CONCAT Dsdr,"sfn" TO Dddr,"dfn" ON Udn The file named dfn on drive ddre will contain the contents of both dfn and sfn after the concatenation. For example: CONCAT D0,"YOURFILE" TO D0,"MYFILE" This will result in MYFILE, containing the data from the old MYFILE, and YOURFILE being concatenated. YOURFILE will remain unchanged. NOTE The concatenation feature of COPY disk command and CONCAT direct command are valid only for DOS 2. For further information regarding use of BASIC COPY and CONCAT com- mands, refer to the Commodore BASIC 4.0 Reference Manual. RENAME The RENAME command renames an existing file. A file can not already exist with the file name specified in the command or the FILE EXISTS error message will be generated. 24 The format for RENAME is: PRINT#1fn,"RENAMEdr:nfn=ofn" Where: dr = the disk drive on which the diskette is located (0). nfn = the new name of the file. ofn = the old name of the file. 1fn = a logical file number. You assign this number arbitrarily and it may be any whole number between 1 and 255. NOTE The letter R is a legal abbreviation for RENAME. RENAME - (BASIC 4.0 Direct Command) The RENAME direct command in BASIC 4.0 performs the same function as RENAME disk command. The format is: RENAME Ddr,"ofn" TO "nfn" (Ddr=0) ON Udn NOTE Close any open files before using the RENAME command since the disk will not execute this com- mand on any active files. For further information on the RENAME comand, please refer to the Com- modore BASIC 4.0 Reference Manual. SCRATCH The SCRATCH command erases unwanted files from the specified diskette and its directory. You can erase one file, several files, or all the files on a diskette. The format for SCRATCH is: PRINT#1fn,"Sdr:fn,dr:fn...dr:fn" Where: dr = is the disk drive to be searched (0). fn = is the name of the file to be erased. 25 To erase one file, enter the entire name of the file: Example: PRINT#1,"S0:ACCT" To erase several files with unrelated names, enter the entire name of each file to be deleted: Example: PRINT#1,"S0:ACCT,0:CUSTOMER,0:INV" To erase several files at one time where names have something in common, refer to the rules in APPENDIX B concernig pattern matching. You may erase all files on a diskette using pattern matching as in the following example: Example: PRINT#1,"S0:*" SCRATCH - (BASIC 4.0 Direct Command) SCRATCH direct command in BASIC 4.0 performs the same function as SCRATCH disk command. The format is: SCRATCH Ddr,"jn" ON Udn Where: dr = drive number (0) fn = filename of file to be scratched dn = device number (Defaults to 8) Pattern matching rules may be used with this command. As with the HEADER command, there is a built-in safety feature that queries the user: ARE YOU SURE? A positive response permits the file to be SCRATCHed while a negative response aborts the opertation. For a complete description of the SCRATCH direct command, please refer to your BASIC 4.0 reference manual. 26 Chapter 4 BASIC COMMANDS FOR DATA HANDLING BASIC COMMANDS ASSOCIATED WITH FLOPPY DISK DRIVES The BASIC commands described in this chapter, allow the user to communicate with and transfer data to an dfrom the disk drive. These commands are available for ALL versions of Commodore BASIC: OPEN1fn,8,sa,"dr:fn,t,r/w" VERIFY"dr:fn",8 CLOSE1fn PRINT#1,fn LOAD"dr:fn",8 GET#1fn SAVE"dr:fn",8 INPUT#1fn These commands are available ONLY in BASIC 4.0: DOPEN#1fn,"fn" DSAV"fn" DCLOSE#1fn RECORD#1fn,R,B DLOAD"fn" 27 Where: lfn = logical file number (any number between 1 and 255) fn = file name supplied by user Dx = dr = disk drive number: both Dx and dr default to 0 8 = device number (8 for disk, 2 for second cassette, 4 for printer) sa = secondary address t = file type All upper-case characters shown in format are essential for the proper execution of a command and must by typed by user. These commands are entered via the keyboard using unshifted characters only. On the CBM Business Model they will appear in lower case. BASIC 3.0 commands are upward compatible with BASIC 4.0 commands. Each command will be defined along with a brief example to illustrate their use As soon as your dual drive floppy disk is attached to your computer and has passed the performance test, we encourage you to try the examples and precedures. SAVE and DSAVE (Writing A Program To A Diskette) If a program is in computer memory, it can be moved to a diskette for storage. This is accomplished with the SAVE (any Commodore BASIC) or DSAVE (BASIC 4.0) commands. Any data transferred with the SAVE or DSAVE commands are automatically designated by the DOS as a program (PRG) file. Both commands transfer PRG files from the coputer's memory to the specified diskette. You must specify the dirve number, the program name, and the device number. The device number will default to device 1 which is the tape unit if it is not specified. The format of SAVE is: SAVE"dr:fn",dn Where: dr = is the disk drive number. It must be 0. fn = is any file name of 16 characters or less you wish to assign to the file to be transferred to the diskette. Blanks are counted as characters. dn = is the device number (in this case 8). This following example illustrates creating a one line program, SAVEing it on the diskette under the name TESTPROG, and VERIFYing that it is resident on disk. 28 Example: 10?"THIS IS A TEST" SAVE"0:TESTPROG",8 VERIFY"0:TESTPROG",8 The DSAVE command performs the same function as SAVE, but is valid only with a Commodore disk system and BASIC 4.0. The format is: DSAVE"fn"Ddr On Udn This command will save a file named "fn" on the floppy disk in drive 0. The file name, "fn", may be any name of 16 characters or less. LOAD and DLOAD (Reading A Program From A Diskette) A program stored on diskette may be loaded into memory using the LOAD (any Commodore BASIC) or DLOAD (BASIC 4.0) commands. The LOAD and DLOAD commands transfer PRG files from the specified diskette to the computer's memory. You must specify the drive number, the program name, and the device number. The device number will default to unit 1 which is the cassette unit. The format for LOAD is: LOAD"dr:fn",dn Where: dr = the drive number from which you are loading data. It must be 0. fn = the file name prevously specified in the SAVE command and/ or stored in the disk directory. dn = the device number (in this case 8) The following example illustrates how a program is loaded from the diskette into the computer memory, then executed. To do this example, first type NEW and depress RETURN key to clear your computer's memory so that you can see that is really works. Don't confuse the NEW command in BASIC with the NEW disk command used to format your disk. Example: LOAD"0:TESTPROG",8 READY. RUN THIS IS A TEST 29 The DLOAD command transfers performs the same function as LOAD, but is specifically designed for a Commodore disk unit using BASIC 4.0. The device number will default to 8 if not specified. The drive number will default to 0 if not specified. DLOAD"fn",Ddr A successful LOAD or DLOAD closes all open files. Therefore you must give a new OPEN command in order to continue communicating with the disk drive command and error channel. VERIFY The format for VERIFY command is: VERIFY"dr:fn",8 This command verifies that a file named "fn" stored on a floppy disk contains the same information which is stored in the computer's memory. This command is the same as the VERIFY command used with the tape cassette. Once again, dr refers to the drive number (zero). Note that the format for this command speci- fies that the drive number be place dbefore the filename. The 8 at the end of this command isthe device number (8 for disk, 2 for second tape cassette). STEP 1: Write a short program and save it on a diskette in drive 1 under the name "test" using the procedure described under the section on SAVE. NOTE It is important that the program in memory is not changed in any way between the save and verfy operations. STEP 2: Type: VERIFY"0:TEST",8 Once verified, the screen displays: VERIFY "0:TEST",8 SEARCHING FOR 0:TEST VERIFYING OK READY. If a verify error occurs reSAVE the program and verify it again. VERIFY may also be used in the format: VERIFY"*",8 30 In order to perform verification of the last file saved without re-typing the filename, confirm by following these steps: STEP 1: Write a short program and save it. STEP 2: Clear the screen. STEP 3: Type VERIFY"*",8 The VERIFY function will be performed comparing the last file saved to the contents of memory. OPEN This command sets up a correspondence between a logical file number and a file which exists on disk. It also reserves the buffer space within the disk unit for operations on the file being opened. The format of the complete OPEN command is: OPENlfn,dn,sa,"dr:fn,ft,mode" Where: lfn = the logical file number dn = the device number; in this case 8 sa = the secondary address. It may be any number from 2 to 14 and may be used either for input or output as specified in mode. See note below. dr = the drive number: 0 fn = the name of the file. ft = the file type. It may be SEQ (for sequential), USR (for user), REL (for relative) or PRG (for program). mode describes how the channel is to be used. It may be either READ (R) or WRITE (W). NOTE Secondary address 15 is the command and error channel and has special uses which are discussed in subsequent chapters. Secondary addresses 0 and 1 are reserved by the operating systems (BASIC and DOS) for LOADing and SAVEing programs. Examples: OPEN2,8,2,"0:FILE1,SEQ,WRITE" OPEN3,8,9,"0:TESTDATA,PRG,WRITE" OPEN8,8,8,"0:NUM,USR,READ" 31 The contents of an existing file may be replaced by preceding the drive number with an at sign (@) in the OPEN command. OPEN3,8,5,"@0:JDATA,USR,WRITE" If the specified file does not exist, then normal OPENing procedures are illustrated in these examples: Example 1: FL$="0:FILEA,SEQ,READ" OPEN1,8,14,FL$ Example 2: FL$="0:FILEA" OPEN1,8,14,FL$+",SEQ,WRITE" The preceding methods are convenient when it is necessary to open several channels to the same file name. DOPEN The DOPEN command is available only to BASIC 4.0 users. DOPEN may be used to create relative files or sequential files of fixed length. The format of DOPEN is: DOPEN#lfn,"fn",Ddr,Lrl,(,ONUdn)(,W) Where: lfn, fn, and dr are the same as defined for OPEN. Lrl defines the record length as equal to rl (relative files only) ONUdn specifies the device number equal to dn (with default device being 8) W may be specified tomena write mode. If W is not specified for sequential files, the file will be opened to read. CLOSE The CLOSE command closes a file opened by the OPEN comand. Its format is: CLOSE lfn Where: lfn = the logical file number of a file opened by the OPEN com- mand. 32 Always close a file after working with it.You are ot allowed to have more than ten open files in the computer and five in the disk drives, so it is prudent to make a habit of closing files as soon as possible. This way you will always have the maximum number of files available for use. DCLOSE The DCLOSE command is available only to BASIC 4.0 users. This command closes files opened with the DOPEN command. The format for DCLOSE is: DCLOSE#lfn Where: lfn = the logical file number of the file to be closed. The DCLOSE command mayalso be used in this format: DCLOSE ONUdn Where: dn = the device number of the disk unit (defaults to 8). When used in this form, DCLOSE command closes all active disk files on the specified unit. The following examples illustrate some applications of DCLOSE command: Example 1: DCLOSE Close all files currently OPEN. Example 2: DCLOSE#5 Close only logical file 5. CLOSING THE COMMAND CHANNEL Closing the command channel closes all channesl associated with the disk drive. No other part of the logical file environment is affected. That is, the computer does not recognize that the files have been closed. The following example illustrates a situation in which several channels are closed down by a single CLOSE command. 33 Example: OPEN1,8,15 The command channel is opened. OPEN3,8,2,"0:FILE1,SEQ,WRITE" Data Channels are opened for OPEN4,8,2,"0:FILE2,SEQ,WRITE" writing. PRINT#3,"IMPORTANT DATA" PRINT#4,"MORE DATA" OPEN3,4 A channel is opened to the printer by mistake. ?FILE OPEN ERROR? An error message is displayed on the screen. READY. Since there was an error, all logical files in the computer are closed, but the channels in the disk drive are still open. To close the disk channels, type: OPEN1,8,15 CLOSE1 Now all data channels in the disk drive are properly closed. CLOSING THE DATA CHANNEL The CLOSE command closes a file an the data or command channel associated with it. When ever you close a file opened with a write channel, the closing of that file writes the final block of data to the disk and updates the disk directory. When you close a file opened with a read channel, that channel is simply closed down. NOTE When a drive is initialized with INITIALIZE, NEW or VALIDATE, all channels associated with that drive are deleted. These commands shoul not be executed when there are any files open since the files will be disrupted. PRINT# The PRINT# command transmits a disk command string to the drive. The format of PRINT# is: PRINT#lfn,"commandstring" 34 Where: lfn = a file previosly opened using secondary address 15 "commandstring" = disk handling or disk file handling commands. These disk commands are discussed in detail in Chapter 3 of this manual. PRINT# may also be used to transmit data to previously-opened sequential or relative file. A semicolon must be used as a terminator for each PRINT# state- ment when using BASIC 3.0 to avoid sending extraneous line feeds to the diskette. These charracters are written to the diskette by the BASIC PRINT# routine as part of the data terminator. It is important to be aware of this fact because the carriage return alone is seen as a terminator by the DOS. The line feed is then stored in the file as the first charcter in the next record. To avoid this, use the following format: Example: PRINT#2,"JONESABC";CHR$(13); The CHR$(13) is the carriage return necessary for the proper termination of the record on the disk. When this record is input, the result will be JONESABC which is the desired result. BASIC 4.0 users do not need to follow this procedure (though no harmful effects will result from it). In BASIC 4.0, any file opened with lfn less than 128 will automatically suppress the line feed. The following format may then be used: PRINT#lfn,A$ This will produce the desired value of A$ for the record, and will not interfere with the next record. Several variables may be written to the disk at the same time. The format: PRINT#lfn,A$,B$,C$ will result in a single variable (A$+B$+C$) being retrieved by the input command. The format: PRINT#lfn,A$CHR$(13)B$CHR$(13)C$ will result in the variables A$, B$, and C$ being separated by carriage retrns, and they may then be input as separate variables. 35 INPUT# The INPUT# command is used to transfer information from an IEEE device such as the disk drive into computer memory. INPUT# is valid only when used in a program and only when referencing a logical file that has been OPENed for input. The format for INPUT# is: INPUT#lfn,A$ or INPUT#lfn,A Where: lfn = a file previously opened using secondary address 15 A$ = a string variable which will contain the data transferred. A = a numeric variable which will contain the date transferred. INPUT# may also be used to transfer several strings of data at one time: INPUT#lfn, A$,B$,C$ Where: A$, B$, C$ will contain the data transferred from the disk. In this format, the data strings must have been separated by carriage returns (CHR$(13)) at the time they were written tho the disk in order to be retrieved separately. No single string may contain more than 80 characters if it is to be INPUT. EXAMPLE 1: * * 20 INPUT#2,A * Input the next data item which must be in numeric form and assign the value to variable A. EXAMPLE 2: * * 10 INPUT#8,A$ * Input the next data item as a string and assign it to variable A$. EXAMPLE 3: * * 60 INPUT#7,B,C$ * Input the next two data items and assign the first to numeric variable B and the second to string variable C$. For strings longer than 80 characters, the GET# command must be used. 36 GET# The GET# command is used to transfer individual bytes of information from an IEEE device such as the disk drive into computer memory. GET# is valid ony when used in a program and only when referencing a file that has been OPENed. The format for GET# is: GET#lfn,A$ Where: lfn = a file previously opened using secondary address 15 A$ = a string variable which will contain the data transferred. GET# may also be used to transfer several bytes of information, which is useful for retrieving strings which have been written to the disk in a format which is unacceptable of the INPUT# command (strings longer than 80 characters). For example: 10 AA$="" 20 FOR I=1 TO 254 30 GET#lfn,A$ 40 AA$=AA$+A$ 50 NEXT is a program segment which would result in a string of length 254 being trans- ferred from the disk (logical file number lfn) to the computer memory and stored in the variable AA$. RECORD# The RECORD# command is used prior to a PRINT#, INPUT#, or GET# in order to position the file pointer to the desired record (and byte) of a relative file. For example, if record pointer is set beyond the last record and PRINT# is used, the appropriate number of records are generated to expand the file to the desired record. RECORD# is available only to users equipped with BASIC 4.0. The format is: RECORD#lfn,r,b Where: lfn = a logical file number of a file previously opened with the DOPEN command r = the desired record number. r may be either a variable name or value, however if r is a variable name, it must appear enclosed in parenthesis. I<=r<=65535 37 b = the byte position desired within the record. Bye positioning is optional. l<=<=254 The following example illustrates how RECORD command is used with INPUT#: Example: 10 RECORD#1,120 Using the RECORD command to select the record. 20 INPUT#1,A$ Input the next data item as a string and assign it to variable A$. A detailed example of the usage of the RECORD command for relative file manipulation is found in Chapter 6. QUICKLOAD FEATURE (BASIC 4.0) This command feature is valid with DOS 2 and BASIC 4.0. It loads the first file on the disk into memory. To ensure that the first program on the diskette is accessed, the command must be the first disk command given after a cold start. STEP 1: Turn the computer OFF, then ON. STEP 2: Make sure the disk contains a program as the first file, and the drive door is closed. STEP 3: Simultaneously press the SHIFT and RUN/STOP keys. The computer will initialize the disk, search for the first program, and load it. *** commodore basic 4.0 *** 31743 bytes free ready dL"* searching for 0:* loading ready. run When using this feature the computer will automatically execute the DLOAD and RUN commands and it is not necessary to enter either command. 38 MOVING A TAPE PROGRAM TO DISK This example illustrates a session with the computer, a tape cassette and a disk drive. The purpose is to copy a cassette program to a diskette. The program is then read from the diskette to the computer's memory and printed. It is assumed that the BASIC program was previously stored on the cassette. Example: LOAD"DEMO" PRESS PLAY ON TAPE #1 Load the file from the cassette tape to the computer's memory. OK SEARCHING FOR DEMO FOUND DEMO LOADING READY SAVE"0:DEMO",8 Create a program file containing the program VERIFY"0:DEMO",8 on diskette. READY. NEW Erase everything from memory. (The NEW command in BASIC will clear memory; the NEW disk command will format a disk.) LOAD"0:DEMO",8 Load the program back into the computer's SEARCHING FOR 0:DEMO memory. LOADING READY. RUN Run the program to verify it has been loaded. 39 40 Chapter 5 ADVANCED DISK PROGRAMMING This chapter provides detailed information about DOS structure and disk utility commands. The utility commands provide the programmer with low-level func- tions that may be used for special applications such as special disk handling routines and random access techniques. COMMODORE DISK OPERATING SYSTEM (DOS) The DOS file interface controller is responsible for managing all information between the disk controller and the IEEE-488 bus. Most disk I/O is performed on a pipelined basis, resulting in a faster response to a requested operation. The file system is organized by channels which are opened with the BASIC OPEN statement. When executed with the OPEN statement, the DOS assigns a workspace to each channel and allocates either one or two disk I/O buffer areas. If either the workspace or the buffer is not available, a NO CHANNEL error is generated. The DOS also uses the channel structure to search the directory, and to delete and copy files. 41 The job queue is the vital link between the two controllers. Jobs are initiated on the file side by providing the disk controller with sector header and type of operation information. The disk controller seeks the optimum job and attempts execution. An error condition is then returned in place of the job command. If the job is unsuccessful, the file side re-enters the job a given number of times, depending upon the operation, before generating an error message. The secondary address given in the OPEN statement is used by DOS as the channel number. The number the user assigns to a channel is only a reference number that is used to access the work areas, and is not related to the DOS ordering of channels. The LOAD and SAVE statements transmit secondary addresses of 0 and 1, respectively. The DOS automatically interprets these secondary addresses as LOAD and SAVE functions. Unless these functions are desired when opening files, avoid secondary addresses of 0 and 1. The remaining numbers, 2 through 14, may be used as secondary addresses to open up to five channels for data. Secondary address 15 is used to access the command channel for error messages, INPUT and GET statements and for "memory" commands. DISK UTILITY COMMAND SET The disk utility command set consists of the following commands: Commands Abbreviations General Format BLOCK-READ B-R "B-R:"ch;dr;t;s BLOCK-WRITE B-W "B-W:"ch;dr;t;s BLOCK-EXECUTIVE B-E "B-E:"ch;dr;t;s BUFFER-POINTER B-P "B-P:"ch;p BLOCK-ALLOCATE B-A "B-A:"dr;t;s BLOCK-FREE B-F "B-F:"dr;t;s memory-write M-W "M-W"adl/adh/nc/data memory-read M-R "M-R"adl/adh memory-execute M-E "M-E"adl/adh USER U "Ui:parms" Where: ch = the channel number in DOS: identical to the secondary address in the associated OPEN statement. dr = the drive number: 0 t = the track number: 1 through 35 p = the pointer position for the buffer pointer. 42 adl = the low byte of the address*. adh = the high byte of the address*. nc = the number of characters: 1 through 34. data = the actual data in hexadecimal. This is transmitted by using the CHR$ function, i.e. CHR$(1) would send the binary equivalent of hexadecimal 01, (decimal 1). i = the index to the User Table. parms = the parameters associated with the U command. (optional). The values used in conjunction with the memory commands exist as hexadecimal values and must be transmitted as CHR$(n), where n is the decimal equivalent of the desired hexadecimal value. NOTE When using variables, the format must have only the command in quotes. For example: "B-R:"ch;dr;t;s correct "B-R:ch,dr,t,s" incorrect To avoid confusion, it is good practice to use this format when using variables or constants. As implied in the preceding format, these commands may be abbreviated to the first character of each of the key words. Abbreviations only are accepted for those commands shown in lower case. The parameters associated with each position if a colon is not present. The example following shows four ways that the same block-read command may be given. Example: "BLOCK-READ:"2;0;4;0 "B-R"2;0;4;0 "B-READ:"2;0;4;0 Parameters following the key words within quotation marks may be separated by any combination of the following characters: Character Name Keyboard Representation Skip Space Space bar Comma , 43 The use of these characters permits sending both ASCII strings and integers. Parameters not within the confines of quotation marks should be separated by semicolons (;). In the following discussions, a PRINT# is assumed in all examples. BLOCK-READ This diskette utility command provides direct access to any block on a diskette in either disk drive. Used in conjunction with other block commands, a random access file system may be created through BASIC. This command finds the character pointer in the 0 position of the block. When a character in this position is accessed with GET# or INPUT#, an End-or-Identify (EOI) is sent. This termi- nates an INPUT# and sets the Status Word (ST) to 64 in the computer. The format "B-R"ch;dr;t;s is illustrated in the following example. Example: "B-R"5;0;18;0 Reads the block from track 18, sector 0 into channel 5 buffer area. After using BLOCK READ to transfer the data to the buffer, the data may be transferred to memory by INPUT# or GET# from the logical file opened to that disk channel (i.e. , using that secondary address). The U1 command described under USER is similar to the BLOCK-READ command. BLOCK-WRITE When this command is initiated, the current buffer pointer is used as the last character pointer and is placed in the 0 position of the new buffer. The buffer is then written to the indicated block on the diskette and the buffer pointer is left in position 1. The format "B-W"ch;dr;t;s is illustrated in the following example. Example: "B-W"7;0;35;10 Writes channel 7 buffer to the block on track 35, sector 10: BLOCK- WRITE is not available with DOS 2. 44 BLOCK-EXECUTE This command allows part of the DOS or user designed routines to reside on disk and be loaded into disk drive memory and executed. B-E is really a B-R with an addition. The file Interface Controller begins execution of the contents after the block is read into a buffer. Execution must be terminated with a return from the subroutine (RTS) instruction. Future system extensions or user-created functions may implement this command. The format "B-E"ch;dr;t;s is illustrated in the following example. Example: "B-E"6;0;1;10 Reads a block from track 1, sector 10 into channel 6 buffer and executes its contents beginning at postition 0 in the buffer. BUFFER-POINTER This command changes the pointer associated with the given channel to a new value. This is useful when accessing particular fields of a record in a block or, if the block is divided into records, individual reecords may be set for transmitting or receiving data. The format "B-P"ch;p is illustrated in the following example. Example: "B-P"2;0 Sets channel 2 pointer to the beginning of the data area in the direct access buffer. BLOCK-ALLOCATE The appropriate BAM is updated in the DOS memory to reflect the indicated block as allocated (used). In future operations, the DOS skips over the allocated block when saving programs or writing sequential files. The updated BAM is written to diskette upon the closure of a write file or the closure of a direct access channel. If the block requested has been previously allocated, the error channel indicates the next available block (increasing track and sector numbers) with a NO 45 BLOCK error. If there are no blocks available that are greater in number than the one requested, zeroes are displayed as track and sector parameter. The format "B-A"dr;t;s is illustrated in the following example. Example: "B-A"0;10;0 Requests that block (sector) 0 of track 10 be flagged as allocated on the diskette. NOTE The error channel should always be checked when using block allocate, so that if the block is already allocated, it will not be overwritten. If the block is allocated, the error message will also indicate the next available block. Example: INPUT#15,EN,EM$,ET,ES Reads the next track and sector, respectively, into ET and ES, assuming that lfn=15 has been previously OPENed to the disk error channel. MEMORY All three MEMORY commands are byte oriented so that the user can utilize machine language programs. BASIC statements may be used to access informa- tion through the MEMORY commands by using the CHR$ function. The sys- tem accepts only M-R, M-W, and M-E. Neither verbose spelling nor the use of the colon (;) is permitted. Memory-Write This command provides direct access to the DOS memory. Special routines may be downloaded to the disk drive through this command and then executed using the MEMORY-EXECUTE command or one of the USER (U) commands. Up to 34 bytes may be deposited with each use of the command. The low byte of the address must precede the high byte of the address. 46 The format "M-W"adl/adh/nc/data is illustrated in the following example. Example: "M-W"CHR$(00)CHR$(18)CHR$(4)CHR$(4)CHR$(32)CHR$(0)CHR$(17)CHR$(96) Writes four bytes to buffer 2 ($1200 or decimal 4608). MEMORY-READ The byte pointed to by the address in the command string may be accessed with this command. Variables from the DOS or the contents of the buffers may also be read with this command. The M-R command changes the contents of the error channel since it is used for transmitting the information to the computer. The next GET# from the error channel (secondary address 15) transmits the byte. An INPUT# should not be executed from the error channel after a MEMORY-READ command until a DOS command other than one of the MEMORY commands is executed. The format "M-R"adl/adh is illustrated in the following example. Example: "M-R"CHR$(128)CHR$(0) Accesses the byte located at ($0080 or decimal 128). MEMORY-EXECUTE Subroutines in the DOS memory may be executed with this command. To return to the DOS, terminate the subroutine with RTS ($60). The format "M-E"adl/adh is illustrated in the following example. Example: "M-E"CHR$(128)CHR$(49) Requests the execution of code beginning at $3180. USER This command provides a link to 6502 machine code according to a jump table pointed to by the special user pointer. Refer to Table 3. The second character in this command is used as an index to the table. The ASCII character 0 through 9 or A through 0 may be used. Zero sets the user pointer to a standard jump table that contains links to special routinres. 47 The special USER commands U1 (or UA) and U2 (or UB) can be used to replace the BLOCK-READ and the BLOCK-WRITE commands. The format for U1 is: "U1:"ch;dr;t;s U1 forces the character count (buffer pointer) to 255 and reads an entire block into memory. This allows complete access to all bytes in the block. The format for U2 is: "U2:"ch;dr;t;s U2 writes a buffer to a block on the disk without changing the contents of position 0 as B-W does. This is useful when a block is to be read in (with B-R) and updated (B-P to the field and PRINT#), then written back to diskette with U2. Refer to the random access example in Chapter 6 for an application of the U1 and U2 commands. Table 3 STANDARD JUMP TABLE ---------------------------------------------------------------------------------------------------------------- | | | Alternate | | User User | | Designation Designation Function | | | | U1 UA BLOCK-READ replacement | | U2 UB BLOCK-WRITE replacement | | U3 UC jump to $0500 | | U4 UD jump to $0503 | | U5 UE jump to $0506 | | U6 UF jump to $0509 | | U7 UG jump to $050C | | U8 UH jump to $050F | | U9 UI jump to $0065 | | U: UJ power up vector | | | |--------------------------------------------------------------------------------------------------------------- U3 through U9 commands are user defined. the locations jumped to are located in the buffer areas of RAM and routines may be written to reside there and downloaded using the M-W command. 48 FILE TYPES Program (PRG) This type contains data eencoded in CBM BASIC format. Files of this type may be read into the CBM computer with the LOAD command and written to the disk with either the SAVE command or with the "S" command (from the editor). Sequential (SEQ) or User (USR) This type contains data encoded in any manner. Sequential files are used by the CBM editor and are also used by various custom program written by users. Relative (REL) This type contains data encoded in any manner. Associated with the relative file will be side sectors which hold pointers to data within the relative file. (Refer to Chapter 6 for further description.) Block, Directory and Bam Formats A data block is addressed by track and sector. A 2031 diskette contains 35 tracks (or rings) numbered 1 to 35. The number of sectors per track will vary (as illustrated in table 4) due to differences in track circumference and recording frequency. The 2031 maintains a system file on track 18 which contains the BAM, diskette name, ID and file directory. The BAM, resident in the first 128 bytes of sector 0, monitors available and occupied storage locations on the diskette. The last 128 bytes of sector 0 are used to store the diskette name and ID. The file directory begins on the next sector, sector 1. 49 Table 4 BLOCK DISTRIBUTION BY TRACK ---------------------------------------------------------------------------------------------------------------- | | | Block or | | Track number Sector Range Total | | | | 1 to 17 0 to 20 21 | | 18 to 24 0 to 18 19 | | 25 to 30 0 to 17 18 | | 31 to 35 0 to 16 17 | | | ---------------------------------------------------------------------------------------------------------------- Any block on a diskette may be examined by using the program DISPLAY T&S, provided on the TEST/DEMO diskette. Tables 5 and 6 will assist the user in interpreting information obtained using the DISPLAY T&S program. Table 5 2031 BAM FORMAT ---------------------------------------------------------------------------------------------------------------- | Track 18, Sector 0 | ---------------------------------------------------------------------------------------------------------------- | Byte Contents Definition | | | | 0,1 18,01 Track and sector of first | | directory block | | | | 2 65 ASCII character A indi- | | cating DOS 2 format | | | | 3 0 Null flag for future DOS | | use | | | | 4-143 Bit map of available | | blocks for tracks 1-35* | ---------------------------------------------------------------------------------------------------------------- | *1=available block | | 0=block not available | | (each bit represents one block) | ---------------------------------------------------------------------------------------------------------------- 50 Table 6 2031 DIRECTORY HEADER ---------------------------------------------------------------------------------------------------------------- | Track 18, Sector 0 | ---------------------------------------------------------------------------------------------------------------- | Byte Contents Definition | | | | | | 144-161 Disk name padded with | | shifted spaces. | | | | | | 162-163 Disk ID. | | | | | 164 160 Shifted space. | | | | | 165, 166 50,65 ASCII representation for | | 2A which is DOS version | | and format type. | | | | 166-167 160 Shifted spaces. | | | | | 171-255 0 Nulls, not used. | ---------------------------------------------------------------------------------------------------------------- |Note: ASCII characters may appear in locations 180 through 191 on | | some diskettes. | ---------------------------------------------------------------------------------------------------------------- Table 7 DIRECTORY FORMATS ---------------------------------------------------------------------------------------------------------------- | Track 18, Sector 1 | ---------------------------------------------------------------------------------------------------------------- | Byte Definition | | | | 0,1 Track and sector of next directory block | | | | 2-31 * File entry 1 | | | | 34-63 * File entry 2 | | | | 66-95 * File entry 3 | | | | 98-127 * File entry 4 | | | | 130-159 * File entry 5 | | | | 162-191 * File entry 6 | | | | 194-223 * File entry 7 | | | | 226-255 * File entry 8 | | | ---------------------------------------------------------------------------------------------------------------- *STRUCTURE OF SINGLE DIRECTORY ENTRY (page 52) 51 Table 8 FORMAT OF DIRECTORY ENTRY ---------------------------------------------------------------------------------------------------------------- | Byte Contents Definition | | | | 0 128+type file type OR'ed with $80 to indicate prop- | | perly closed file. | | TYPES: 0 = DELetetd | | 1 = SEQuential | | 2 = PRoGram | | 3 = USeR | | 4 = RELative | | 1,2 Track and sector of 1st data block. | | 3-18 File name padded with shifted spaces. | | 19,20 Relative file only: track and sector for first | | side sector block. | | 21 Relative file only: Record size. | | 22-25 unused. | | 26,27 Track and sector of replacement file when | | OPEN@ is in effect. | |28,29 Number of blocks in file low byte, high | | byte. | ---------------------------------------------------------------------------------------------------------------- Table 9 SEQUENTIAL FORMAT ---------------------------------------------------------------------------------------------------------------- | Byte Definition | | | | 0,1 Track and sector of next sequential data block | | 2-255 254 bytes of data with carriage returns as record terminators | ---------------------------------------------------------------------------------------------------------------- Table 10 PROGRAM FILE FORMAT ---------------------------------------------------------------------------------------------------------------- | Byte Definition | | | | 0,1 Track and sector of next block in program file. | | 2-255 254 bytes of program information stored in CBM BASIC | | format (with keywords tokenized). End of file is marked by | | three zero bytes. | ---------------------------------------------------------------------------------------------------------------- 52 [ picture of disk - p52.jpg ] Figure 4. Expanded View of a Single Sector Figure 4 illustrates an expanded view of a single sector on a diskette formatted for the 2031. In addition to other information, each sector contains a data block consisting of 256 stored characters. Blocks within the same file are linked together by means of a two-character block pointer. By pointing to the location of the next data block, block pointers enable the system to retrieve data from non-contiguous blocks. Retrieving the first data block within a file triggers a search for the next data block which, in turn, utilizes block pointers to locate related block until the entire file is assembled and made available for display. All PRG, SEQ, and USR files utilize this format. 53 [blank page] 54